<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GtkFileChooserDialog</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GTK+ 2 Reference Manual">
<link rel="up" href="SelectorWidgets.html" title="Selectors (File/Font/Color/Input Devices)">
<link rel="prev" href="GtkFileChooserButton.html" title="GtkFileChooserButton">
<link rel="next" href="GtkFileChooserWidget.html" title="GtkFileChooserWidget">
<meta name="generator" content="GTK-Doc V1.18 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="GtkFileChooserButton.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="SelectorWidgets.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GTK+ 2 Reference Manual</th>
<td><a accesskey="n" href="GtkFileChooserWidget.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#GtkFileChooserDialog.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#GtkFileChooserDialog.description" class="shortcut">Description</a>
                   | 
                  <a href="#GtkFileChooserDialog.object-hierarchy" class="shortcut">Object Hierarchy</a>
                   | 
                  <a href="#GtkFileChooserDialog.implemented-interfaces" class="shortcut">Implemented Interfaces</a>
</td></tr>
</table>
<div class="refentry">
<a name="GtkFileChooserDialog"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="GtkFileChooserDialog.top_of_page"></a>GtkFileChooserDialog</span></h2>
<p>GtkFileChooserDialog — A file chooser dialog, suitable for "File/Open" or "File/Save" commands</p>
</td>
<td valign="top" align="right"><img src="filechooser.png"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="GtkFileChooserDialog.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include &lt;gtk/gtk.h&gt;

struct              <a class="link" href="GtkFileChooserDialog.html#GtkFileChooserDialog-struct" title="struct GtkFileChooserDialog">GtkFileChooserDialog</a>;
<a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *         <a class="link" href="GtkFileChooserDialog.html#gtk-file-chooser-dialog-new" title="gtk_file_chooser_dialog_new ()">gtk_file_chooser_dialog_new</a>         (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *title</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a> *parent</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkFileChooser.html#GtkFileChooserAction" title="enum GtkFileChooserAction"><span class="type">GtkFileChooserAction</span></a> action</code></em>,
                                                         <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_button_text</code></em>,
                                                         <em class="parameter"><code>...</code></em>);
<a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *         <a class="link" href="GtkFileChooserDialog.html#gtk-file-chooser-dialog-new-with-backend" title="gtk_file_chooser_dialog_new_with_backend ()">gtk_file_chooser_dialog_new_with_backend</a>
                                                        (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *title</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a> *parent</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkFileChooser.html#GtkFileChooserAction" title="enum GtkFileChooserAction"><span class="type">GtkFileChooserAction</span></a> action</code></em>,
                                                         <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *backend</code></em>,
                                                         <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_button_text</code></em>,
                                                         <em class="parameter"><code>...</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="GtkFileChooserDialog.object-hierarchy"></a><h2>Object Hierarchy</h2>
<pre class="synopsis">
  <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>
   +----<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GInitiallyUnowned">GInitiallyUnowned</a>
         +----<a class="link" href="GtkObject.html" title="GtkObject">GtkObject</a>
               +----<a class="link" href="GtkWidget.html" title="GtkWidget">GtkWidget</a>
                     +----<a class="link" href="GtkContainer.html" title="GtkContainer">GtkContainer</a>
                           +----<a class="link" href="GtkBin.html" title="GtkBin">GtkBin</a>
                                 +----<a class="link" href="GtkWindow.html" title="GtkWindow">GtkWindow</a>
                                       +----<a class="link" href="GtkDialog.html" title="GtkDialog">GtkDialog</a>
                                             +----GtkFileChooserDialog
</pre>
</div>
<div class="refsect1">
<a name="GtkFileChooserDialog.implemented-interfaces"></a><h2>Implemented Interfaces</h2>
<p>
GtkFileChooserDialog implements
 AtkImplementorIface,  <a class="link" href="GtkBuildable.html" title="GtkBuildable">GtkBuildable</a> and  <a class="link" href="GtkFileChooser.html" title="GtkFileChooser">GtkFileChooser</a>.</p>
</div>
<div class="refsect1">
<a name="GtkFileChooserDialog.description"></a><h2>Description</h2>
<p>
      <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> is a dialog box suitable for use with
      "File/Open" or "File/Save as" commands.  This widget works by
      putting a <a class="link" href="GtkFileChooserWidget.html" title="GtkFileChooserWidget"><span class="type">GtkFileChooserWidget</span></a> inside a <a class="link" href="GtkDialog.html" title="GtkDialog"><span class="type">GtkDialog</span></a>.  It exposes
      the <span class="type">GtkFileChooserIface</span> interface, so you can use all of the
      <a class="link" href="GtkFileChooser.html" title="GtkFileChooser"><span class="type">GtkFileChooser</span></a> functions on the file chooser dialog as well as
      those for <a class="link" href="GtkDialog.html" title="GtkDialog"><span class="type">GtkDialog</span></a>.
    </p>
<p>
      Note that <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> does not have any methods of its
      own.  Instead, you should use the functions that work on a
      <a class="link" href="GtkFileChooser.html" title="GtkFileChooser"><span class="type">GtkFileChooser</span></a>.
    </p>
<div class="example">
<a name="gtkfilechooser-typical-usage"></a><p class="title"><b>Example 45. Typical usage</b></p>
<div class="example-contents">
<p>
	In the simplest of cases, you can the following code to use
	<a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> to select a file for opening:
      </p>
<pre class="programlisting">
GtkWidget *dialog;
dialog = gtk_file_chooser_dialog_new ("Open File",
				      parent_window,
				      GTK_FILE_CHOOSER_ACTION_OPEN,
				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
				      GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
				      NULL);
if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
    open_file (filename);
    g_free (filename);
  }
gtk_widget_destroy (dialog);
      </pre>
<p>
        To use a dialog for saving, you can use this:
      </p>
<pre class="programlisting">
GtkWidget *dialog;
dialog = gtk_file_chooser_dialog_new ("Save File",
				      parent_window,
				      GTK_FILE_CHOOSER_ACTION_SAVE,
				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
				      GTK_STOCK_SAVE, GTK_RESPONSE_ACCEPT,
				      NULL);
gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
if (user_edited_a_new_document)
  {
    gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (dialog), default_folder_for_saving);
    gtk_file_chooser_set_current_name (GTK_FILE_CHOOSER (dialog), "Untitled document");
  }
else
  gtk_file_chooser_set_filename (GTK_FILE_CHOOSER (dialog), filename_for_existing_document);
if (gtk_dialog_run (GTK_DIALOG (dialog)) == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    filename = gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (dialog));
    save_to_file (filename);
    g_free (filename);
  }
gtk_widget_destroy (dialog);
      </pre>
</div>
</div>
<br class="example-break"><div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="gtkfilechooserdialog-response-codes"></a>Response Codes</h2></div></div></div>
<p>
      <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> inherits from <a class="link" href="GtkDialog.html" title="GtkDialog"><span class="type">GtkDialog</span></a>, so buttons that
      go in its action area have response codes such as
      <a class="link" href="GtkDialog.html#GTK-RESPONSE-ACCEPT:CAPS"><span class="type">GTK_RESPONSE_ACCEPT</span></a> and <a class="link" href="GtkDialog.html#GTK-RESPONSE-CANCEL:CAPS"><span class="type">GTK_RESPONSE_CANCEL</span></a>.  For example, you
      could call <a class="link" href="GtkFileChooserDialog.html#gtk-file-chooser-dialog-new" title="gtk_file_chooser_dialog_new ()"><code class="function">gtk_file_chooser_dialog_new()</code></a> as follows:
    </p>
<pre class="programlisting">
GtkWidget *dialog;
dialog = gtk_file_chooser_dialog_new ("Open File",
				      parent_window,
				      GTK_FILE_CHOOSER_ACTION_OPEN,
				      GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
				      GTK_STOCK_OPEN, GTK_RESPONSE_ACCEPT,
				      NULL);
    </pre>
<p>
      This will create buttons for "Cancel" and "Open" that use stock
      response identifiers from <a class="link" href="GtkDialog.html#GtkResponseType" title="enum GtkResponseType"><span class="type">GtkResponseType</span></a>.  For most dialog
      boxes you can use your own custom response codes rather than the
      ones in <a class="link" href="GtkDialog.html#GtkResponseType" title="enum GtkResponseType"><span class="type">GtkResponseType</span></a>, but <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> assumes that
      its "accept"-type action, e.g. an "Open" or "Save" button,
      <span class="emphasis"><em>will</em></span> have one of the following response
      codes:
      <a name="gtkfilechooserdialog-responses"></a></p>
<table border="0" summary="Simple list" class="simplelist">
<tr><td><a class="link" href="GtkDialog.html#GTK-RESPONSE-ACCEPT:CAPS"><span class="type">GTK_RESPONSE_ACCEPT</span></a></td></tr>
<tr><td><a class="link" href="GtkDialog.html#GTK-RESPONSE-OK:CAPS"><span class="type">GTK_RESPONSE_OK</span></a></td></tr>
<tr><td><a class="link" href="GtkDialog.html#GTK-RESPONSE-YES:CAPS"><span class="type">GTK_RESPONSE_YES</span></a></td></tr>
<tr><td><a class="link" href="GtkDialog.html#GTK-RESPONSE-APPLY:CAPS"><span class="type">GTK_RESPONSE_APPLY</span></a></td></tr>
</table>
<p>
    </p>
<p>
      This is because <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> must intercept responses
      and switch to folders if appropriate, rather than letting the
      dialog terminate — the implementation uses these known
      response codes to know which responses can be blocked if
      appropriate.
    </p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
	To summarize, make sure you use a <a class="link" href="GtkFileChooserDialog.html#gtkfilechooserdialog-responses">stock response
	code</a> when you use <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> to ensure
	proper operation.
      </p>
</div>
</div>
</div>
<div class="refsect1">
<a name="GtkFileChooserDialog.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="GtkFileChooserDialog-struct"></a><h3>struct GtkFileChooserDialog</h3>
<pre class="programlisting">struct GtkFileChooserDialog;</pre>
<p>
</p>
</div>
<hr>
<div class="refsect2">
<a name="gtk-file-chooser-dialog-new"></a><h3>gtk_file_chooser_dialog_new ()</h3>
<pre class="programlisting"><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *         gtk_file_chooser_dialog_new         (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *title</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a> *parent</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkFileChooser.html#GtkFileChooserAction" title="enum GtkFileChooserAction"><span class="type">GtkFileChooserAction</span></a> action</code></em>,
                                                         <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_button_text</code></em>,
                                                         <em class="parameter"><code>...</code></em>);</pre>
<p>
Creates a new <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a>.  This function is analogous to
<a class="link" href="GtkDialog.html#gtk-dialog-new-with-buttons" title="gtk_dialog_new_with_buttons ()"><code class="function">gtk_dialog_new_with_buttons()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>title</code></em> :</span></p></td>
<td>Title of the dialog, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>parent</code></em> :</span></p></td>
<td>Transient parent of the dialog, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>action</code></em> :</span></p></td>
<td>Open or save mode for the dialog</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>first_button_text</code></em> :</span></p></td>
<td>stock ID or text to go in the first button, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a new <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
<hr>
<div class="refsect2">
<a name="gtk-file-chooser-dialog-new-with-backend"></a><h3>gtk_file_chooser_dialog_new_with_backend ()</h3>
<pre class="programlisting"><a class="link" href="GtkWidget.html" title="GtkWidget"><span class="returnvalue">GtkWidget</span></a> *         gtk_file_chooser_dialog_new_with_backend
                                                        (<em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *title</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a> *parent</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GtkFileChooser.html#GtkFileChooserAction" title="enum GtkFileChooserAction"><span class="type">GtkFileChooserAction</span></a> action</code></em>,
                                                         <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *backend</code></em>,
                                                         <em class="parameter"><code>const <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gchar"><span class="type">gchar</span></a> *first_button_text</code></em>,
                                                         <em class="parameter"><code>...</code></em>);</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p><code class="literal">gtk_file_chooser_dialog_new_with_backend</code> has been deprecated since version 2.14 and should not be used in newly-written code. Use <a class="link" href="GtkFileChooserDialog.html#gtk-file-chooser-dialog-new" title="gtk_file_chooser_dialog_new ()"><code class="function">gtk_file_chooser_dialog_new()</code></a> instead.</p>
</div>
<p>
Creates a new <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a> with a specified backend. This is
especially useful if you use <a class="link" href="GtkFileChooser.html#gtk-file-chooser-set-local-only" title="gtk_file_chooser_set_local_only ()"><code class="function">gtk_file_chooser_set_local_only()</code></a> to allow
non-local files and you use a more expressive vfs, such as gnome-vfs,
to load files.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>title</code></em> :</span></p></td>
<td>Title of the dialog, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>parent</code></em> :</span></p></td>
<td>Transient parent of the dialog, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>action</code></em> :</span></p></td>
<td>Open or save mode for the dialog</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>backend</code></em> :</span></p></td>
<td>The name of the specific filesystem backend to use.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>first_button_text</code></em> :</span></p></td>
<td>stock ID or text to go in the first button, or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>. <span class="annotation">[<acronym title="NULL is ok, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a new <a class="link" href="GtkFileChooserDialog.html" title="GtkFileChooserDialog"><span class="type">GtkFileChooserDialog</span></a>
</td>
</tr>
</tbody>
</table></div>
<p class="since">Since 2.4</p>
</div>
</div>
<div class="refsect1">
<a name="GtkFileChooserDialog.see-also"></a><h2>See Also</h2>
<p>
      <a class="link" href="GtkFileChooser.html" title="GtkFileChooser"><span class="type">GtkFileChooser</span></a>, <a class="link" href="GtkDialog.html" title="GtkDialog"><span class="type">GtkDialog</span></a>
    </p>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.18</div>
</body>
</html>